<!DOCTYPE html>
<html prefix="og: http://ogp.me/ns#">
<head>
  <meta charset="UTF-8">
  <title>Customizing Atom</title>
  <link data-turbolinks-track="true" href="../../assets/application-b86a2086c99917c6bf2a9d74b4038381.css" media="all" rel="stylesheet" />
  <script data-turbolinks-track="true" src="../../assets/application-c3106c6fe52ccec6f26495730a478cca.js"></script>
  <meta content="authenticity_token" name="csrf-param" />
<meta content="yzXUiWH6GiCHbvbJOg7usjzA7LawyxwB+oJHEcWTOIM=" name="csrf-token" />
  <script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-3769691-35', 'atom.io');
  ga('send', 'pageview');

</script>

  <meta property="og:url" content="https://atom.io/" />
<meta property="og:site_name" content="Atom" />
<meta property="og:title" content="A hackable text editor for the 21st Century" />
<meta property="og:description" content="At GitHub, we’re building the text editor we’ve always wanted: hackable to the core, but approachable on the first day without ever touching a config file. We can’t wait to see what you build with it." />
<meta property="og:type" content="website" />
<meta property="og:author" content='https://www.facebook.com/GitHub' />
<meta property="og:image" content="http://og.github.com/atom-logo/atom-logo@1200x1200.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="1200" />
<meta property="og:image" content="http://og.github.com/atom-mark/atom-mark@1200x630.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

  <meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:site" content="@AtomEditor" />
<meta property="twitter:creator" content='@github' />
<meta property="twitter:title" content="Atom" />
<meta property="twitter:description" content="A hackable text editor for the 21st Century" />
<meta property="twitter:image:src" content="http://og.github.com/atom-logo/atom-logo@1200x630.png" />
<meta property="twitter:image:width" content="1200" />
<meta property="twitter:image:height" content="630" />

  <link rel="shortcut icon" href="../../favicon.ico"/>
</head>
<body>

  <div class="footer-push">
    
    

    <header class="header">
  <div class="wrapper">
    <h1 title="Atom">
      <a href="../../index.html" class="logo"></a>
    </h1>

    <ul class="navigation">
      <li><a class="" href="../../packages.html">Packages</a></li>
      <li><a class="is-selected" href="../latest/index.html">Documentation</a></li>
      <li><a href="http://blog.atom.io">Blog</a></li>
      <li><a href="../../faq.html">FAQ</a></li>
      <li><a class="" href="http://atom.io/contact">Contact</a></li>
    </ul>
  </div>
</header>


    <div class="wrapper documents content-push">
  <div class="columns">
    <div class="column main-column markdown">
        <h1>
<a name="customizing-atom" href="customizing-atom.html#customizing-atom"></a>Customizing Atom</h1>

<p>To change a setting, configure a theme, or install a package just open the
Settings view in the current window by pressing <code>cmd+,</code>.</p>

<h2>
<a name="changing-the-theme" href="customizing-atom.html#changing-the-theme"></a>Changing The Theme</h2>

<p>Atom comes with both light and dark UI themes as well as several syntax themes.
You are also encouraged to <a href="creating-a-theme.html">create or fork</a> your own theme.</p>

<p>To change the active theme just open the Settings view (<code>cmd-,</code>) and select the
<code>Themes</code> section from the left hand side. You will see a drop-down menu to
change the active <em>Syntax</em> and <em>UI</em> themes.</p>

<p>You can also install more themes from here by browsing the featured themes or
searching for a specific theme.</p>

<h2>
<a name="installing-packages" href="customizing-atom.html#installing-packages"></a>Installing Packages</h2>

<p>You can install non-bundled packages by going to the <code>Packages</code> section on left
hand side of the Settings view (<code>cmd-,</code>). You will see several featured packages
and you can also search for packages from here. The packages listed here have
been published to <a href="../../packages.html">atom.io</a> which is the official
registry for Atom packages.</p>

<p>You can also install packages from the command line using <code>apm</code>.</p>

<p>Check that you have <code>apm</code> installed by running the following command in your
terminal:</p>

<pre lang="sh"><code>apm help install
</code></pre>

<p>You should see a message print out with details about the <code>apm install</code> command.</p>

<p>If you do not, launch Atom and run the <em>Atom &gt; Install Shell Commmands</em> menu
to install the <code>apm</code> and <code>atom</code> commands.</p>

<p>You can also install packages by using the <code>apm install</code> command:</p>

<ul>
<li><p><code>apm install &lt;package_name&gt;</code> to install the latest version.</p></li>
<li><p><code>apm install &lt;package_name&gt;@&lt;package_version&gt;</code> to install a specific version.</p></li>
</ul><p>For example <code>apm install emmet@0.1.5</code> installs the <code>0.1.5</code> release of the
<a href="https://github.com/atom/emmet">Emmet</a> package into <code>~/.atom/packages</code>.</p>

<p>You can also use <code>apm</code> to find new packages to install:</p>

<ul>
<li><p><code>apm search coffee</code> to search for CoffeeScript packages.</p></li>
<li><p><code>apm view emmet</code> to see more information about a specific package.</p></li>
</ul><h2>
<a name="customizing-key-bindings" href="customizing-atom.html#customizing-key-bindings"></a>Customizing Key Bindings</h2>

<p>Atom keymaps work similarly to stylesheets. Just as stylesheets use selectors
to apply styles to elements, Atom keymaps use selectors to associate keystrokes
with events in specific contexts. Here's a small example, excerpted from Atom's
built-in keymaps:</p>

<pre lang="coffee"><div class="line"><span class="source coffee"><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>.editor</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>enter</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>editor:newline</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span> </span></span></div><div class="line"><span class="source coffee"><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>body</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>ctrl-b</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>core:move-left</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>ctrl-f</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>core:move-right</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div></pre>

<p>This keymap defines the meaning of <code>enter</code> in two different contexts. In a
normal editor, pressing <code>enter</code> emits the <code>editor:newline</code> event, which causes
the editor to insert a newline. But if the same keystroke occurs inside of a
select list's mini-editor, it instead emits the <code>core:confirm</code> event based on
the binding in the more-specific selector.</p>

<p>By default, <code>~/.atom/keymap.cson</code> is loaded when Atom is started. It will always
be loaded last, giving you the chance to override bindings that are defined by
Atom's core keymaps or third-party packages.</p>

<p>You can open this file in an editor from the <em>Atom &gt; Open Your Keymap</em> menu.</p>

<p>You'll want to know all the commands available to you. Open the Settings panel
(<code>cmd-,</code>) and select the <em>Keybindings</em> tab. It will show you all the keybindings
currently in use.</p>

<h2>
<a name="advanced-configuration" href="customizing-atom.html#advanced-configuration"></a>Advanced Configuration</h2>

<p>Atom loads configuration settings from the <code>config.cson</code> file in your <em>~/.atom</em>
directory, which contains CoffeeScript-style JSON:</p>

<pre lang="coffee"><div class="line"><span class="source coffee"><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>core</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>excludeVcsIgnoredPaths</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="constant language boolean true coffee"><span>true</span></span></span></div><div class="line"><span class="source coffee"><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>editor</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>fontSize</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="constant numeric coffee"><span>18</span></span></span></div></pre>

<p>The configuration itself is grouped by the package name or one of the two core
namespaces: <code>core</code> and <code>editor</code>.</p>

<p>You can open this file in an editor from the <em>Atom &gt; Open Your Config</em> menu.</p>

<h3>
<a name="configuration-key-reference" href="customizing-atom.html#configuration-key-reference"></a>Configuration Key Reference</h3>

<ul>
<li>
<code>core</code>

<ul>
<li>
<code>disabledPackages</code>: An array of package names to disable</li>
<li>
<code>excludeVcsIgnoredPaths</code>: Don't search within files specified by <em>.gitignore</em>
</li>
<li>
<code>ignoredNames</code>: File names to ignore across all of Atom</li>
<li>
<code>projectHome</code>: The directory where projects are assumed to be located</li>
<li>
<code>themes</code>: An array of theme names to load, in cascading order</li>
</ul>
</li>
<li>
<code>editor</code>

<ul>
<li>
<code>autoIndent</code>: Enable/disable basic auto-indent (defaults to <code>true</code>)</li>
<li>
<code>autoIndentOnPaste</code>: Enable/disable auto-indented pasted text (defaults to <code>false</code>)</li>
<li>
<code>nonWordCharacters</code>: A string of non-word characters to define word boundaries</li>
<li>
<code>fontSize</code>: The editor font size</li>
<li>
<code>fontFamily</code>: The editor font family</li>
<li>
<code>invisibles</code>: Specify characters that Atom renders for invisibles in this hash

<ul>
<li>
<code>tab</code>: Hard tab characters</li>
<li>
<code>cr</code>: Carriage return (for Microsoft-style line endings)</li>
<li>
<code>eol</code>: <code>\n</code> characters</li>
<li>
<code>space</code>: Leading and trailing space characters</li>
</ul>
</li>
<li>
<code>normalizeIndentOnPaste</code>: Enable/disable conversion of pasted tabs to spaces</li>
<li>
<code>preferredLineLength</code>: Identifies the length of a line (defaults to <code>80</code>)</li>
<li>
<code>showInvisibles</code>: Whether to render placeholders for invisible characters (defaults to <code>false</code>)</li>
<li>
<code>showIndentGuide</code>: Show/hide indent indicators within the editor</li>
<li>
<code>showLineNumbers</code>: Show/hide line numbers within the gutter</li>
<li>
<code>softWrap</code>: Enable/disable soft wrapping of text within the editor</li>
<li>
<code>softWrapAtPreferredLineLength</code>: Enable/disable soft line wrapping at <code>preferredLineLength</code>
</li>
<li>
<code>tabLength</code>: Number of spaces within a tab (defaults to <code>2</code>)</li>
</ul>
</li>
<li>
<code>fuzzyFinder</code>

<ul>
<li>
<code>ignoredNames</code>: Files to ignore <em>only</em> in the fuzzy-finder</li>
</ul>
</li>
<li>
<code>whitespace</code>

<ul>
<li>
<code>ensureSingleTrailingNewline</code>: Whether to reduce multiple newlines to one at the end of files</li>
<li>
<code>removeTrailingWhitespace</code>: Enable/disable striping of whitespace at the end of lines (defaults to <code>true</code>)</li>
</ul>
</li>
<li>
<code>wrap-guide</code>

<ul>
<li>
<code>columns</code>: Array of hashes with a <code>pattern</code> and <code>column</code> key to match the
the path of the current editor to a column position.</li>
</ul>
</li>
</ul><h3>
<a name="quick-personal-hacks" href="customizing-atom.html#quick-personal-hacks"></a>Quick Personal Hacks</h3>

<h3>
<a name="initcoffee" href="customizing-atom.html#initcoffee"></a>init.coffee</h3>

<p>When Atom finishes loading, it will evaluate <em>init.coffee</em> in your <em>~/.atom</em>
directory, giving you a chance to run arbitrary personal CoffeeScript code to
make customizations. You have full access to Atom's API from code in this file.
If customizations become extensive, consider <a href="http://atom.io/docs/v0.60.0/creating-packages">creating a package</a>.</p>

<p>You can open this file in an editor from the <em>Atom &gt; Open Your Init Script</em>
menu.</p>

<p>This file can also be named <em>init.js</em> and contain JavaScript code.</p>

<h3>
<a name="stylesless" href="customizing-atom.html#stylesless"></a>styles.less</h3>

<p>If you want to apply quick-and-dirty personal styling changes without creating
an entire theme that you intend to publish, you can add styles to the
<em>styles.less</em> file in your <em>~/.atom</em> directory.</p>

<p>You can open this file in an editor from the <em>Atom &gt; Open Your Stylesheet</em> menu.</p>

<p>For example, to change the color of the cursor, you could add the following
rule to your <em>~/.atom/styles.less</em> file:</p>

<pre lang="less"><div class="line"><span class="source css less"><span class="entity other attribute-name class css"><span>.editor</span></span><span> </span><span class="entity other attribute-name class css"><span>.cursor</span></span><span> </span><span class="meta brace curly less"><span>{</span></span></span></div><div class="line"><span class="source css less"><span>  </span><span class="support type property-name css"><span>border-color</span></span><span>: pink;</span></span></div><div class="line"><span class="source css less"><span class="meta brace curly less"><span>}</span></span></span></div></pre>

<p>Unfamiliar with LESS? Read more about it <a href="http://www.lesscss.org">here</a>.</p>

<p>This file can also be named <em>styles.css</em> and contain CSS.</p>
    </div>
    <div class="column sidebar documents-toc">
      <select class="js-doc-version-switcher version-switcher">
  <option value="v0.69.0">v0.69.0</option>
<option value="v0.68.0">v0.68.0</option>
<option value="v0.67.0">v0.67.0</option>
<option value="v0.66.0">v0.66.0</option>
<option value="v0.65.0">v0.65.0</option>
<option value="v0.64.0">v0.64.0</option>
<option value="v0.63.0">v0.63.0</option>
<option value="v0.62.0">v0.62.0</option>
<option value="v0.61.0">v0.61.0</option>
<option selected="selected" value="v0.60.0">v0.60.0</option>
<option value="v0.59.0">v0.59.0</option>
<option value="v0.58.0">v0.58.0</option>
<option value="v0.57.0">v0.57.0</option>
<option value="v0.56.0">v0.56.0</option>
<option value="v0.55.0">v0.55.0</option>
<option value="v0.54.0">v0.54.0</option>
<option value="v0.53.0">v0.53.0</option>
<option value="v0.51.0">v0.51.0</option>
<option value="v0.50.0">v0.50.0</option>
<option value="v0.49.0">v0.49.0</option>
<option value="v0.48.0">v0.48.0</option>
<option value="v0.47.0">v0.47.0</option>
<option value="v0.46.0">v0.46.0</option>
<option value="v0.45.0">v0.45.0</option>
<option value="v0.44.0">v0.44.0</option>
<option value="v0.41.0">v0.41.0</option>
<option value="v0.40.0">v0.40.0</option>
<option value="0.52.0">0.52.0</option>
</select>


      <ul class="navigation">
        <li><a href="" class="is-selected">Documentation</a></li>
        <li><a href="../api/v0.60.0/api/index.html">API</a></li>
      </ul>

      <hr />

      <form accept-charset="UTF-8" action="/docs/v0.60.0/search" method="get"><div style="margin:0;padding:0;display:inline"><input name="utf8" type="hidden" value="&#x2713;" /></div>
        <input class="sidebar-search-field" id="q" name="q" placeholder="Search documentation" type="text" value="" />
</form>
      <h2>
<a name="guides" href="customizing-atom.html#guides"></a>Guides</h2>

<ul>
<li><a href="getting-started.html">Getting Started</a></li>
<li><a href="customizing-atom.html">Customizing Atom</a></li>
<li><a href="creating-a-package.html">Creating a Package</a></li>
<li><a href="creating-a-theme.html">Creating a Theme</a></li>
<li><a href="publishing-a-package.html">Publishing a Package</a></li>
<li><a href="converting-a-text-mate-bundle.html">Converting a TextMate Bundle</a></li>
<li><a href="converting-a-text-mate-theme.html">Converting a TextMate Theme</a></li>
<li><a href="contributing.html">Contributing</a></li>
</ul><h3>
<a name="advanced-topics" href="customizing-atom.html#advanced-topics"></a>Advanced Topics</h3>

<ul>
<li><a href="advanced/configuration.html">Configuration</a></li>
<li><a href="advanced/keymaps.html">Keymaps</a></li>
<li><a href="advanced/serialization.html">Serialization</a></li>
<li><a href="advanced/view-system.html">View System</a></li>
</ul>
    </div>
  </div>
</div>


    <div class="footer-pad"></div>
  </div>

  <footer>
  <div class="footer">
    <div class="wrapper">
      <ul class="footer-left">
        <li><a href="../../terms.html">Terms of Use</a></li>
          <li><a href="http://atom.io/login">Sign in</a></li>
      </ul>

      <div class="footer-right">
        <a href="https://github.com"><span class="octicon octicon-code"></span> with <span class="octicon octicon-heart"></span> by <span class="octicon octicon-logo-github"></span></a>
      </div>
    </div>
  </div>
</footer>

</body>
</html>
